### `CPVT_WordPlace` 结构体概述

`CPVT_WordPlace` 是 PDFium 库中的一个结构体，用于表示 PDF 文档中某个特定文本位置的详细信息。它通过三个整数成员变量来标识文本在文档中的具体位置：段落索引（`nSecIndex`）、行索引（`nLineIndex`）和单词索引（`nWordIndex`）。该结构体提供了多种操作符重载和成员函数，用于比较、移动和重置文本位置。以下是 `CPVT_WordPlace` 的详细功能说明：

#### 成员变量(Member Variables)

1. * *`int32_t nSecIndex = -1;`* *
-**功能 * *：表示段落索引，即文本所在的段落在文档中的位置。
- **说明 * *：段落索引从 0 开始计数， - 1 表示无效或未初始化的段落。

2. * *`int32_t nLineIndex = -1;`* *
-**功能 * *：表示行索引，即文本所在的行在当前段落中的位置。
- **说明 * *：行索引从 0 开始计数， - 1 表示无效或未初始化的行。

3. * *`int32_t nWordIndex = -1;`* *
-**功能 * *：表示单词索引，即文本所在的单词在当前行中的位置。
- **说明 * *：单词索引从 0 开始计数， - 1 表示无效或未初始化的单词。

#### 构造函数(Constructors)

1. * *`CPVT_WordPlace() = default;`* *
-**功能 * *：默认构造函数，创建一个未初始化的 `CPVT_WordPlace` 对象。
- **说明 * *：所有成员变量（`nSecIndex`、`nLineIndex` 和 `nWordIndex`）将被初始化为 - 1，表示无效位置。

2. * *`CPVT_WordPlace(int32_t other_nSecIndex, int32_t other_nLineIndex, int32_t other_nWordIndex)`* *
-**功能 * *：带参数的构造函数，使用给定的段落索引、行索引和单词索引初始化 `CPVT_WordPlace` 对象。
- **参数 * *：
- `int32_t other_nSecIndex`：段落索引。
- `int32_t other_nLineIndex`：行索引。
- `int32_t other_nWordIndex`：单词索引。
- **说明 * *：该构造函数允许用户直接指定文本位置的具体信息。

#### 成员函数(Member Functions)

1. * *`void Reset()`* *
-**功能 * *：重置 `CPVT_WordPlace` 对象，将其所有成员变量设置为 - 1，表示无效位置。
- **说明 * *：该函数用于将 `CPVT_WordPlace` 对象恢复到初始状态，通常在需要清除或重新初始化位置时使用。

2. * *`void AdvanceSection()`* *
-**功能 * *：将段落索引递增 1，并将行索引和单词索引重置为初始值。
- **说明 * *：该函数用于移动到下一个段落的起始位置，常用于遍历文档中的多个段落。

3. * *`inline bool operator==(const CPVT_WordPlace & wp) const`* *
-**功能 * *：重载等于运算符，用于比较两个 `CPVT_WordPlace` 对象是否相等。
- **参数 * *：
- `const CPVT_WordPlace & wp`：要比较的另一个 `CPVT_WordPlace` 对象。
- **返回值 * *：返回一个布尔值，`true` 表示两个文本位置相等，`false` 表示不相等。
- **说明 * *：该函数通过比较 `nSecIndex`、`nLineIndex` 和 `nWordIndex` 来判断两个文本位置是否相同。

4. * *`inline bool operator!=(const CPVT_WordPlace & wp) const`* *
-**功能 * *：重载不等于运算符，用于比较两个 `CPVT_WordPlace` 对象是否不相等。
- **参数 * *：
- `const CPVT_WordPlace & wp`：要比较的另一个 `CPVT_WordPlace` 对象。
- **返回值 * *：返回一个布尔值，`true` 表示两个文本位置不相等，`false` 表示相等。
- **说明 * *：该函数通过调用 `operator= = ` 并取反来实现。

5. * *`inline bool operator<(const CPVT_WordPlace & wp) const`* *
  -**功能 * *：重载小于运算符，用于比较两个 `CPVT_WordPlace` 对象的顺序。
  - **参数 * *：
  - `const CPVT_WordPlace & wp`：要比较的另一个 `CPVT_WordPlace` 对象。
  - **返回值 * *：返回一个布尔值，`true` 表示当前对象的文本位置在另一个对象之前，`false` 表示不在其之前。
  - **说明 * *：该函数首先比较 `nSecIndex`，如果相同则比较 `nLineIndex`，最后比较 `nWordIndex`，确保文本位置的比较是逐层进行的。

  6. * *`inline bool operator>(const CPVT_WordPlace & wp) const`* *
  -**功能 * *：重载大于运算符，用于比较两个 `CPVT_WordPlace` 对象的顺序。
  - **参数 * *：
  - `const CPVT_WordPlace & wp`：要比较的另一个 `CPVT_WordPlace` 对象。
  - **返回值 * *：返回一个布尔值，`true` 表示当前对象的文本位置在另一个对象之后，`false` 表示不在其之后。
  - **说明 * *：该函数通过调用 `operator<` 并取反来实现。

  7. * *`inline bool operator<=(const CPVT_WordPlace & wp) const`* *
  -**功能 * *：重载小于等于运算符，用于比较两个 `CPVT_WordPlace` 对象的顺序。
  - **参数 * *：
  - `const CPVT_WordPlace & wp`：要比较的另一个 `CPVT_WordPlace` 对象。
  - **返回值 * *：返回一个布尔值，`true` 表示当前对象的文本位置在另一个对象之前或相等，`false` 表示在其之后。
  - **说明 * *：该函数通过调用 `operator<` 和 `operator= = ` 来实现。

  8. * *`inline bool operator>=(const CPVT_WordPlace & wp) const`* *
  -**功能 * *：重载大于等于运算符，用于比较两个 `CPVT_WordPlace` 对象的顺序。
  - **参数 * *：
  - `const CPVT_WordPlace & wp`：要比较的另一个 `CPVT_WordPlace` 对象。
  - **返回值 * *：返回一个布尔值，`true` 表示当前对象的文本位置在另一个对象之后或相等，`false` 表示在其之前。
  - **说明 * *：该函数通过调用 `operator>` 和 `operator= = ` 来实现。

  9. * *`inline int32_t LineCmp(const CPVT_WordPlace & wp) const`* *
  -**功能 * *：比较两个 `CPVT_WordPlace` 对象的段落和行索引。
  - **参数 * *：
  - `const CPVT_WordPlace & wp`：要比较的另一个 `CPVT_WordPlace` 对象。
  - **返回值 * *：返回一个整数值，表示段落和行索引的差异：
  - 如果当前对象的段落索引小于另一个对象，则返回负数。
  - 如果当前对象的段落索引大于另一个对象，则返回正数。
  - 如果段落索引相同，则返回行索引的差异。
  - **说明 * *：该函数仅比较段落和行索引，忽略单词索引，常用于需要按行排序的场景。

  ### 功能总结

  `CPVT_WordPlace` 结构体的主要功能包括：

  1. * *文本位置的表示 * *：通过 `nSecIndex`、`nLineIndex` 和 `nWordIndex` 成员变量，`CPVT_WordPlace` 可以精确地表示 PDF 文档中某个文本的位置，具体到段落、行和单词。
  2. * *文本位置的比较 * *：通过重载 `<`、`>`、`< = `、`> = `、`= = ` 和 `! = ` 运算符，`CPVT_WordPlace` 支持对文本位置进行逐层比较，确保文本位置的顺序和相等性判断准确无误。
  3. * *文本位置的移动 * *：`AdvanceSection()` 函数允许用户将文本位置移动到下一个段落的起始位置，方便遍历文档中的多个段落。
  4. * *文本位置的重置 * *：`Reset()` 函数可以将 `CPVT_WordPlace` 对象的所有成员变量重置为 - 1，表示无效位置，常用于清除或重新初始化位置。
  5. * *段落和行的比较 * *：`LineCmp()` 函数专门用于比较两个 `CPVT_WordPlace` 对象的段落和行索引，忽略单词索引，适用于按行排序的场景。

  ### 使用场景

  `CPVT_WordPlace` 主要用于以下场景：

  - **文本选择 * *：在 PDF 文档中选择一段文本时，可以使用 `CPVT_WordPlace` 来表示选择的起始和结束位置。
  - **文本编辑 * *：在编辑 PDF 文档中的文本时，`CPVT_WordPlace` 可以用于标识需要删除、插入或修改的文本位置。
  - **文本搜索 * *：在搜索 PDF 文档中的特定文本时，`CPVT_WordPlace` 可以用于表示匹配到的文本位置，方便后续的高亮显示或进一步操作。
  - **文本遍历 * *：在遍历 PDF 文档中的文本内容时，`CPVT_WordPlace` 可以用于跟踪当前的文本位置，确保遍历过程有序进行。

  通过这些功能，`CPVT_WordPlace` 在 PDF 文档处理过程中能够高效地管理和操作文本位置，确保文本编辑、选择和搜索操作的正确性和效率。// Copyright 2016 The PDFium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com

#ifndef CORE_FPDFDOC_CPVT_WORDPLACE_H_
#define CORE_FPDFDOC_CPVT_WORDPLACE_H_

#include <stdint.h>

struct CPVT_WordPlace {
  CPVT_WordPlace() = default;

  CPVT_WordPlace(int32_t other_nSecIndex,
                 int32_t other_nLineIndex,
                 int32_t other_nWordIndex)
      : nSecIndex(other_nSecIndex),
        nLineIndex(other_nLineIndex),
        nWordIndex(other_nWordIndex) {}

  void Reset() {
    nSecIndex = -1;
    nLineIndex = -1;
    nWordIndex = -1;
  }

  void AdvanceSection() {
    nSecIndex++;
    nLineIndex = 0;
    nWordIndex = -1;
  }

  inline bool operator==(const CPVT_WordPlace& wp) const {
    return wp.nSecIndex == nSecIndex && wp.nLineIndex == nLineIndex &&
           wp.nWordIndex == nWordIndex;
  }
  inline bool operator!=(const CPVT_WordPlace& wp) const {
    return !(*this == wp);
  }
  inline bool operator<(const CPVT_WordPlace& wp) const {
    if (nSecIndex != wp.nSecIndex)
      return nSecIndex < wp.nSecIndex;
    if (nLineIndex != wp.nLineIndex)
      return nLineIndex < wp.nLineIndex;
    return nWordIndex < wp.nWordIndex;
  }
  inline bool operator>(const CPVT_WordPlace& wp) const {
    if (nSecIndex != wp.nSecIndex)
      return nSecIndex > wp.nSecIndex;
    if (nLineIndex != wp.nLineIndex)
      return nLineIndex > wp.nLineIndex;
    return nWordIndex > wp.nWordIndex;
  }
  inline bool operator<=(const CPVT_WordPlace& wp) const {
    return *this < wp || *this == wp;
  }
  inline bool operator>=(const CPVT_WordPlace& wp) const {
    return *this > wp || *this == wp;
  }

  inline int32_t LineCmp(const CPVT_WordPlace& wp) const {
    if (nSecIndex != wp.nSecIndex)
      return nSecIndex - wp.nSecIndex;
    return nLineIndex - wp.nLineIndex;
  }

  int32_t nSecIndex = -1;
  int32_t nLineIndex = -1;
  int32_t nWordIndex = -1;
};

#endif  // CORE_FPDFDOC_CPVT_WORDPLACE_H_
